---
title: Quickstart
description: Turn your Mastra Agents into an agent-native application in 10 minutes.
icon: "lucide/Play"
hideTOC: true
---

import {
  TailoredContent,
  TailoredContentOption,
} from "@/components/react/tailored-content.tsx";
import { CoAgentsEnterpriseCTA } from "@/components/react/coagents/coagents-enterprise-cta.tsx";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
import { CoAgentsDiagram } from "@/components/react/coagents/coagents-diagram.tsx";
import { FaPython, FaJs, FaCloud } from "react-icons/fa";
import SelfHostingCopilotRuntimeCreateEndpoint from "@/snippets/self-hosting-copilot-runtime-create-endpoint.mdx";
import CopilotKitCloudCopilotKitProvider from "@/snippets/copilot-cloud-configure-copilotkit-provider.mdx";
import { Accordions, Accordion } from "fumadocs-ui/components/accordion";
import FindYourCopilotRuntime from "@/snippets/find-your-copilot-runtime.mdx";
import CloudCopilotKitProvider from "@/snippets/coagents/cloud-configure-copilotkit-provider.mdx";
import SelfHostingCopilotRuntimeConfigureCopilotKitProvider from "@/snippets/coagents/self-host-configure-copilotkit-provider.mdx";
import SelfHostingCopilotRuntimeStarter from "@/snippets/self-hosting-copilot-runtime-starter.mdx";
import SelfHostingRemoteEndpoints from "@/snippets/self-hosting-remote-endpoints.mdx";
import {
  UserIcon,
  PaintbrushIcon,
  WrenchIcon,
  RepeatIcon,
  ServerIcon,
} from "lucide-react";
import CopilotUI from "@/snippets/copilot-ui.mdx";

<video
  src="https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/chat-example.mp4"
  className="rounded-lg shadow-xl"
  loop
  playsInline
  controls
  autoPlay
  muted
/>

## Prerequisites

Before you begin, you'll need the following:

- An OpenAI API key
- Node.js 20+
- Your favorite package manager

## Getting started

<Steps>
    <TailoredContent
        className="step"
        id="agent"
        header={
            <div>
                <p className="text-xl font-semibold">Choose your starting point</p>
                <p className="text-base">
                    You can either start fresh with our starter template or integrate CopilotKit into your existing Mastra Agent.
                </p>
            </div>
        }
    >
        <TailoredContentOption
            id="starter"
            title="Start from scratch"
            description="Get started quickly with our ready-to-go starter application."
        >
            <Step>
                ### Run our CLI

                First, we'll use our CLI to create a new project for us.

                ```bash
                npx copilotkit@latest create -f mastra
                ```
            </Step>
            <Step>
                ### Install dependencies

                ```npm
                ```
            </Step>
            <Step>
                ### Configure your environment

                Create a `.env` file and add your OpenAI API key:

                ```plaintext title=".env"
                OPENAI_API_KEY=your_openai_api_key
                ```

                <Callout type="info" title="What about other models?">
                  The starter template is configured to use OpenAI's GPT-4o by default, but you can modify it to use any language model supported by Mastra.
                </Callout>
            </Step>
            <Step>
                ### Start the development server

                <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
                    <Tab value="npm">
                        ```bash
                        npm run dev
                        ```
                    </Tab>
                    <Tab value="pnpm">
                        ```bash
                        pnpm dev
                        ```
                    </Tab>
                    <Tab value="yarn">
                        ```bash
                        yarn dev
                        ```
                    </Tab>
                    <Tab value="bun">
                        ```bash
                        bun dev
                        ```
                    </Tab>
                </Tabs>

                This will start both the UI and agent servers concurrently.
            </Step>
        </TailoredContentOption>
        <TailoredContentOption
            id="bring-your-own"
            title="Use an existing agent"
            description="I already have a Mastra Agent and want to add CopilotKit."
        >
            <Step>
                ### Initialize your Mastra project

                If you don't already have a Mastra project set up, create one:

                ```bash
                npx create-mastra@latest my-agent
                cd my-agent
                ```
            </Step>
            <Step>
                ### Create your Mastra agent

                Create a new agent file in your Mastra project:

                ```ts title="src/mastra/agents/index.ts"
                import { openai } from "@ai-sdk/openai";
                import { Agent } from "@mastra/core/agent";

                export const myAgent = new Agent({
                  name: "My Agent",
                  instructions: "You are a helpful assistant!",
                  model: openai("gpt-4o"),
                });
                ```

                Then export it from your Mastra instance:

                ```ts title="src/mastra/index.ts"
                import { Mastra } from "@mastra/core";
                import { myAgent } from "./agents";

                export const mastra = new Mastra({
                  agents: { myAgent },
                });
                ```

                <Callout type="info" title="What about other models?">
                  This example uses OpenAI's GPT-4o, but you can modify it to use any language model supported by Mastra.
                </Callout>
            </Step>
            <Step>
                ### Configure your environment

                Set your OpenAI API key as an environment variable:

                ```bash
                export OPENAI_API_KEY=your_openai_api_key
                ```
            </Step>
            <Step>
                ### Create your frontend

                CopilotKit works with any React-based frontend. We'll use Next.js for this example.

                ```bash
                npx create-next-app@latest my-copilot-app
                cd my-copilot-app
                ```
            </Step>
            <Step>
                ### Install CopilotKit packages

                ```package-install
                @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/mastra
                ```
            </Step>
            <Step>
                ### Setup Copilot Runtime

                Create an API route to connect CopilotKit to your Mastra agent:

                ```ts title="app/api/copilotkit/route.ts"
                import {
                  CopilotRuntime,
                  ExperimentalEmptyAdapter,
                  copilotRuntimeNextJSAppRouterEndpoint,
                } from "@copilotkit/runtime";
                import { NextRequest } from "next/server";
                import { MastraAgent } from "@ag-ui/mastra"
                import { mastra } from "@/mastra"; // the path to your Mastra instance

                const serviceAdapter = new ExperimentalEmptyAdapter();

                const runtime = new CopilotRuntime({
                  agents: MastraAgent.getLocalAgents({ mastra }),
                });

                export const POST = async (req: NextRequest) => {
                  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
                    runtime,
                    serviceAdapter,
                    endpoint: "/api/copilotkit",
                  });

                  return handleRequest(req);
                };
                ```
            </Step>
            <Step>
                ### Configure CopilotKit Provider

                Wrap your application with the CopilotKit provider:

                ```tsx title="app/layout.tsx"
                import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
                import "@copilotkit/react-ui/styles.css";

                // ...

                export default function RootLayout({ children }: {children: React.ReactNode}) {
                  return (
                    <html lang="en">
                      <body>
                        {/* [!code highlight:3] */}
                        <CopilotKit runtimeUrl="/api/copilotkit" agent="myAgent">
                          {children}
                        </CopilotKit>
                      </body>
                    </html>
                  );
                }
                ```
            </Step>
            <Step>
              ### Add the chat interface

              Add the CopilotSidebar component to your page:

              ```tsx title="app/page.tsx"
              import { CopilotSidebar } from "@copilotkit/react-ui"; // [!code highlight:1]

              export default function Page() {
                return (
                  <main>
                    <h1>Your App</h1>
                    {/* [!code highlight:1] */}
                    <CopilotSidebar />
                  </main>
                );
              }
              ```
            </Step>
            <Step>
                ### Start your UI

                Start the development server:

                <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
                    <Tab value="npm">
                        ```bash
                        npm run dev
                        ```
                    </Tab>
                    <Tab value="pnpm">
                        ```bash
                        pnpm dev
                        ```
                    </Tab>
                    <Tab value="yarn">
                        ```bash
                        yarn dev
                        ```
                    </Tab>
                    <Tab value="bun">
                        ```bash
                        bun dev
                        ```
                    </Tab>
                </Tabs>
            </Step>
        </TailoredContentOption>
    </TailoredContent>
    <Step>
        ### 🎉 Start chatting!

        Your AI agent is now ready to use! Try asking it some questions:

        ```
        What tools do you have access to?
        ```

        ```
        What do you think about React?
        ```

        ```
        Show me some cool things you can do!
        ```

        <Accordions className="mb-4">
            <Accordion title="Troubleshooting">
                - If you're having connection issues, try using `0.0.0.0` or `127.0.0.1` instead of `localhost`
                - Make sure your Mastra agent is running on port 4111
                - Check that your OpenAI API key is correctly set in the `.env` file
            </Accordion>
        </Accordions>
    </Step>
</Steps>

## What's next?

Now that you have your basic agent setup, explore these advanced features:

<Cards>
  <Card
    title="Implement Human in the Loop"
    description="Allow your users and agents to collaborate together on tasks."
    href="/mastra/human-in-the-loop"
    icon={<UserIcon />}
  />
  <Card
    title="Add some generative UI"
    description="Render your agent's progress and output in the UI."
    href="/mastra/generative-ui"
    icon={<PaintbrushIcon />}
  />
  <Card
    title="Setup frontend actions"
    description="Give your agent the ability to call frontend tools, directly updating your application."
    href="/mastra/frontend-actions"
    icon={<WrenchIcon />}
  />
</Cards>
